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CP/M INTERFACE GUIDE 



1. INTRODUCTION 

This manual describes the CP/M system organization including 
the structure of memory, as well as system entry points. The 
intention here is to provide the necessary information required 
to write programs which operate under CP/M, and which use the 
peripheral and disk I/O facilities of the system. 

1.1 CP/M Organization 

CP/M is logically divided into four parts: 

BIOS - the basic I/O system for serial peripheral control 

BDOS - the basic disk operating system primitives 

CCP - the console command processer 

TPA - the transient program area 

The BIOS and BDOS are combined into a single program with a com- 
mon entry point and referred to as the FDOS. The CCP is a dis- 
tinct program which uses the FDOS to provide a human-oriented 
interface to the information which is cataloged on the diskette. 
The TPA is an area of memory (i.e, the portion which is not used 
by the FDOS and CCP) where various non-resident operating system 
commands are executed. User programs also execute in the TPA. 
The organization of memory in a standard CP/M system is shown in 
Figure 1. 

The lower portion of memory is reserved for system information 
(which is detailed in later sections) , including user defined inter 
rupt locations. The portion between tbase and cbase is reserved 
for the transient operating system commands, while the portion 
above cbase contains the resident CCP and FDOS. The last three 
locations of memory contain a jump instruction to the FDOS entry 
point which provides access to system functions. 



1.2 Operation of Transient Programs 



Transient programs (system functions and user-defined programs) 
are loaded into the TPA and executed as follows. The operator 
communicates with the CCP by typing command lines following each 
prompt character. Each command line takes one of the forms: 

"^command 5, 

<command> <filename> 
< command > <f ilename'* ,<f iletype> 



i 
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Figure 1. CP/M Memory Organization 



fbase : 



cbase : 




TPA 



tbase : 



boot: 



System Parameters 

ii n I Li i 



address field of jump is fbase 



entry: 



the principal entry point to FDOS is at location 0005 
which contains a JMP to fbase. The address field at 
location 0006 can be used to determine the size of 
available memory, assuming the CCP is being overlayed. 



Note: The exact addresses for boot, tbase, cbase, fbase, 
and entry vary with the CP/M version (see 
Section 6. for version correspondence) . 
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Where <command> is either a built-in command (e.g., DIR or TYPE) , 
or the name of a transient command or program. If the <command> 
is a built-in function of CP/M, it is executed immediately; other- 
wise the CCP searches the currently addressed disk for a file 
by the name 

< command > . COM 

If the file is found, it is assumed to be a memory image of a 
program which executes in the TP A, and thus implicitly originates 
at tbase in memory (see the CP/M LOAD command) . The CCP loads 
the COM file from the diskette into memory starting at tbase, 
and extending up to address cbase. 

If the <command> is followed by either a <filename> or 
<f ilename>. <f iletype> , then the CCP prepares a file control- 
block (FCB) in the system information area of memory. This FCB 
is in the form required to access the file through the FDOS, and 
is given in detail in Section 3.2. 

The program then executes, perhaps using the I/O facilities 
of the FDOS. If the program uses no FDOS facilities, then the 
entire remaining memory area is available for data used by the 
program. If the FDOS is to remain in memory, then the transient 
program can use only up to location fbase as data.* In any case, 
if the CCP area is used by the transient, the entire CP/M system 
must be reloaded upon the transient's completion. This system 
reload is accomplished by a direct branch to location "boot" in 
memory. 

The transient uses the CP/M I/O facilities to communicate 
with the operator's console and peripheral devices, including 
the floppy disk subsystem. The I/O system is accessed by passing 
a "function number" and an "information address" to CP/M through 
the address marked "entry" in Figure 1. In the case of a disk 
read, for example, the transient program sends the number corres- 
ponding to a disk read, along with the address of an FCB, and 
CP/M performs the operation, returning with either a disk read 
complete indication or an error number indicating that the disk 
operation was unsuccessful. The function numbers and error in- 
dicators are given in detail in Section 3.3. 

1.3 Operating System Facilities 

CP/M facilities which are available to transients are divided 
into two categories: BIOS operations, and BDOS primitives. The 
BIOS operations are listed first:** 

i' 

* Address "entry" contains a jump to the lowest address in the 
FDOS, and thus "entry+1" contains the first FDOS address which 
cannot be overlayed. 

**The device support (exclusive of the disk subsystem) corres- 
ponds exactly to Intel's peripheral definition, including I/O 
port assignment and status byte format (see the Intel manual 
which discusses the Itttellec MDS hardware environment) . 
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Read Console Character 
Write Console Character 
Read Reader Character 
Write Punch Character 
Write List Device Character 
Set I/O Status 
Interrogate Device Status 
Print Console Buffer 
Read Console Buffer 
Interrogate Console Status 

The exact details of BIOS access are given in Section 2. The BDOS 
primitives include the following operations: 

Disk System Reset 
Drive Select 
File Creation 
File Open 
File Close 
Directory Search 
File Delete 
File Rename 
Read Record 
Write Record 

Interrogate Available Disks 
Interrogate Selected Disk 
Set DMA Address 

The details of BDOS access are given in Section 3. 



2. BASIC I/O FACILITIES 

Access to common peripherals is accomplished by passing a 
function number and information address to the BIOS. In general, 
the function number is passed in Register C, while the informa- 
tion address is passed in Register pair D,E. Note that this 
conforms to the PL/M Conventions for parameter passing, and thus 
the following PL/M procedure is sufficient to link to the BIOS 
when a value is returned: 

DECLARE ENTRY LITERALLY '0005H»; /* MONITOR ENTRY */ 

* MON2: PROCEDURE (FUNC, INFO) BYTE; 

DECLARE FUNC BYTE, INFO ADDRESS; 
GO TO ENTRY; 



END MON2; 



M0N1: PROCEDURE (FUNC,INFO); 

DECLARE FUNC BYTE, INFO ADDRESS; 
GO TO ENTRY; 
END MON1 

if no returned value is expected. 

2.1 Direct and Buffered I/O. 

The BIOS entry points are given in Table I. In the case of 
simple character I/O to the console, the BIOS reads the console 
device, and removes the parity bit. The character is echoed back 
to the console, and tab characters (control-I) are expanded to 
tab positions starting at column one and separated by eight char- 
acter positions. The I/O status byte takes the form shown in 
Table I, and can be programmatic ally interrogated or changed. 
The buffered read operation takes advantage of the CP/M line edit 
ing facilities. That is, the program sends the address of a read 
buffer whose first byte is the length of the buffer. The second 
byte is initially empty, but is filled-in by CP/M to the number 
of characters read from the console after the operation (not 
including the terminating carriage-return) . The remaining posi- 
tions are used to hold the characters read from the console. The 
BIOS line editing functions which are performed during this oper- 
ation are given below: 

break - line delete and transmit 

rubout - delete last character typed, and echo 

control-C - system rebout 

control-U - delete entire line 

control-E - return carriage, but do not transmit 
buffer (physical carriage return) 

<cr> - transmit buffer 

The read routine also detects control character sequences other 
than those shown above, and echos them with a preceding " t " 
symbol. The print entry point allows an entire string of symbols 
to be printed before returning from the BIOS. The string is 
terminated by a "$" symbol. 

2.2 A Simple Example 

As an example, consider the following PL/M procedures and 
procedure calls which print a heading, and successively read 
the console buffer. Each console buffer is then echoed back in 
reverse order: 



PRINTCHAR: PROCEDURE (B) ; 

/* SEND THE ASCII CHARACTER B TO THE CONSOLE */ 
DECLARE B BYTE; 
CALL MON1 (2,'B) ; 
END PRINTCHAR; 



CRLF: PROCEDURE; 

/* SEND CARRIAGE-RETURN-LINE-FEED CHARACTERS */ 
CALL PRINTCHAR (ODH); CALL PRINTCHAR (OAH) ; 
END CRLF; 



PRINT: PROCEDURE (A); 

/* PRINT THE BUFFER STARTING AT ADDRESS A */ 
DECLARE A ADDRESS; 
CALL MONl (9, A) ; 
END PRINT; 

DECLARE RDBUFF (130) BYTE; 



READ: PROCEDURE; 

/* READ CONSOLE CHARACTERS INTO ' RDBUFF ' */ 
RDBUFF=128; /* FIRST BYTE SET TO BUFFER LENGTH */ 
CALL MON1 (10, .RDBUFF) ; 
END READ; 

DECLARE I BYTE; 

CALL CRLF; CALL PRINT (./TYPE INPUT LINES $') 

DO WHILE 1; /* INFINITE LOOP-UNTIL CONTROL-C */ 
CALL CRLF; CALL PRINTCHAR ('*'); /* PROMPT WITH '*' */ 
CALL READ; I = RDBUFF (1) ; 

DO WHILE (I := I -1) <> 255; 

CALL PRINTCHAR (RDBUFF ( 1+2 )) ; 

END; 

END; 



The execution of this program might proceed as follows: 



TYPE INPUT LINES 

♦HELLO, 

OLLEH 

♦WALL WALLA WASH } 
HSAW ALLAW ALLAW 
*MOM WOW^ 
WOW MOM 

*tc (system reboot) 
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TABLE I 
BASIC I/O OPERATIONS 



FUNCTION/ 
NUMBER 


ENTRY 
PARAMETERS 


RETURNED 
VALUE 


TYPICAL 
CALL 


lead Console 
1 


None 


ASCII Character 


I = MON2(1,0) 


tfrite Console 
2 


ASCII Character 


None 


CALL MONl(2, 'A') 


Read Reader 
3 


None 


ASCII Character 


I = MON2(3,0) 


tfrite Punch 
4 


ASCII Character 


None 


CALL MONl(4, ' B' ) 


tfrite List 
5 


ASCII Character 


None 


CALL MON1 ( 5 , • C * ) 


Set T/O Status 
7 






Tn^TRTsMOM? 11 Cl\ 
x.kj%d J. /» i. — viyjm \ I f \J ) 


Set I/O Status 
8 


I/O Status Byte 


None 


CALL M0N1 (8, IOSTAT) 


Print Buffer 
9 


Address of 
string termi- 
na ted by ' $ ' 


None 


CALL M0Nl(9, . 'PRINT 
THIS $') 


6.<v\ 


I 
i 
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TABLE I (continued) 



FUNCTION/ 
NUMBER 


ENTRY 
PARAMETERS 


RETURNED 
VALUE 


TYPICAL 
CALL 


Read Buffer 


Address of 
Read Buffer* 

(See Note^ 


Read buffer is 
filled to maxi- 
mum length with 
console charac- 
ters 


CALL MONK 10, 
. RDBUFF) ; 


Interrogate 
Console Ready 

11 


None 


Byte value with 
least signifi- 
cant bit = 1 
(true) if con- 
sole character 
is ready 


I = MON2(11,0) 



Note. 



Read buffer is a sequence of memory locations of the form 



Note. 



m k c 



t ^-current buffer length 
' — Maximum buffer length 

The I/O status byte is defined as three fields A,B,C, and D 

2b 2b 2b 2b 



B 



MSB 



LSB 



requiring two bits each, listed from most significant to least 
significant bit, which define the current device assignment as 
follows: 



D 

Console 



0 TTY ^ 

1 CRT \ 

2 BATCHJ 



"0 TTY 
C = ) 1 FAST READER 
Reader \ 2 



'0 TTY 
B = I 1 FAST PUNCH 
Punch \ 2 
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3. DISK I/O FACILITIES 

The BDOS section of CP/M provides access to files stored on 
diskettes. The discussion which follows gives the overall file 
organization, along with file access mechanisms. 

3.1 File Organization 

CP/M implements a named file structure on each diskette, pro- 
viding a logical organization which allows any particular file to 
contain any number of records, from completely empty, to the full 
capacity of a diskette. Each diskette is logically distinct, 
with a compLete operating system, disk directory, and file data 
area. The disk file names are in two parts: the < filename > 
which can be from one to eight alphanumeric characters, and the 
< filetype> which consists of zero through three alphanumeric 
characters. The < filetype > names the generic category of a par- 
ticular file, while the < filename > distinguishes a particular 
file within the category. The <f iletype > s listed below give 
some generic categories which have been established, although 
they are generally arbitrary: 

ASM assembler source file 

ppn assembler listing file 

HEX assembler or PL/M machine code 
in "hex" format 

BAS BASIC Source file 

INT BASIC Intermediate file 

COM Memory image file (i.e., "Command" 

file for transients, produced by LOAD) 

BAK Backup file produced by editor 
(see ED manual) 

$$$ Temporary files created and normally 
erased by editor and utilities 

Thus, the name 

X.ASM 

is interpreted as an assembly language source file by the CCP 
with < filename> X. 

The files in CP/M are organized as a logically contiguous se- 
quence of 128 byte records (although the records may not be phys- 
ically contiguous on the diskette) , which are normally read or 
written in sequential order. Random access is allowed under CP/M 
however, as described in Section 3.4. No particular format with- 
in records is assumed by CP/M, although some transients expect 
particular formats: 



10 

(1) Source files are considered a sequence of 
ASCII characters, where each "line" of the 
source file is followed by carriage-return- 
line-feed characters. Thus, one 128 byte 
CP/M record could contain several logical 
lines of source text. Machine code "hex" 
tapes are also assumed to be in this for- 
mat, although the loader does not require 
the carriage-return-line-feed characters. 
End of text is given by the character con- 
trol-z, or real end-of-file returned by 
CP/M. 

and 

(2) COM files are assumed to be absolute machine 
code in memory image form, starting at tbase 
in memory. In this case, control-z is not 
considered an end of file, but instead is 
determined by the actual space allocated 

to the file being accessed. 

3.2 File Control Block Format 

Each file being accessed through CP/M has a corresponding 
file control block (FCB) which provides name and allocation 
information for all file operations. The FCB is a 33-byte area 
in the transient program's memory space which is set up for each 
file. The FCB format is given in Figure 2. When accessing CP/M 
files, it is the programmer's responsibility to fill the lower 
16 bytes of the FCB, along with the CR field. Normally, the FN 
and FT fields are set to the ASCII < filename > and < filetype > , 
while all other fields are set to zero. Each FCB describes up 
to 16K bytes of a particular file (0 to 128 records of 128 bytes 
each), and, using automatic mechanisms of CP/M, up to 15 addi- 
tional extensions of the file can be addressed. Thus, each FCB 
can potentially describe files up to 256K bytes (which is slightly 
larger than the diskette capacity). 

FCB's are stored in a directory area of the diskette, and are 
brought into central memory before file operations (see the OPEN 
and MAKE commands) then updated in memory as file operations pro- 
ceed, and finally recorded on the diskette at the termination of 
the file operation (see the CLOSE command) . This organization 
makes CP/M file organization highly reliable, since diskette file 
integrity can only be disrupted in the unlikely case of hardware 
failure during update of a single directory entry. 

It should be noted that the CCP constructs an FCB for all 
transients by scanning the remainder of the line following the 
transient name for a < filename> or <f ilenarae>. <f iletype> com- 
bination. Any field not specified is assumed to be all blanks. 
A properly formed FCB is set up at location tfcb (see Section 6), 
with an assumed I/O buffer at tbuff. The transient can use tfcb 
as an address in subsequent input or output operations on this 
file. 



In addition to the default fcb which is set-up at address tfcb, 
CCP also constructs a second default fcb at address tfcb +16 (i.e., 
disk map field of the fcb at tbase) . Thus, if the user types 



the 
the 



PROGNAME X.ZOT Y.ZAP 

the file PPDGNAME.COM is loaded to the TP A, and the default fcb at tfcb 
is initialized to the filename X with filetype ZOT. Since the user typed 
a second file name, the 16 byte area beginning at tfcb^ + 16 10 is also 
initialized with the filename Y and filetype ZAP. It is the responsibility 
of the program to move this second filename and filetype to another area 
(usually a separate file control block) before opening the file which 
begins at tbase, since the open operation will fill the disk map portion, 
thus overwriting the second name and type. 

If no file names were specified in the original command, then the 
fields beginning at tfcb and tfcb + 16 both contain blanks (20H) . If 
one file name was specified, then the field at tfcb + 16 contains blanks. 
If the filetype is omitted, then the field is assumed to contain blanks. 
In all cases, the CCP translates lower case alphabetics to upper case 
to be consistent with the CP/M file naming conventions. 

As an added programming convenience, the default buffer at tbuff 
is initialized to hold the entire command line past the program name. 
Address tbuff contains the number of characters, and tbuff+1, tbuff+2, 

contain the remaining characters up to, but not including, the 
carriage return. Given that the above command has been typed at 
the console, the area beginning at tbuff is set up as follows: 

tbuff: 

+0 +1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11+12 +13 +14 +15 
12 J6 X . Z 0 T Y>' Y . ZAP ? ? ? 



where 12 is the number of valid characters (in binary) , and # represents 
an ASCII blank. Characters are given in ASCII upper case, with un- 
initialized memory following the last valid character. 

Again, it is the responsibility of the program to extract the infor- 
mation from this buffer before any file operations are performed since 
the FDOS uses the tbuff area to perform directory functions. 

In a standard CP/M system, the following values are assumed: 

boot: 0000H bootstrap load {warm start) 

entry: 0005H entry point to FDOS ' 

tfcb: 005CH first default file control block 

tfcb+16 006CH second file name 

tbuff 0080H default buffer address 

tbase: 0100H base of transient area 
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Figure 2, File Control Block Format 



0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 27 28 2 9 30 3 1 32 



ET 



FN 



FT EX RC 



DM 



NR 



FIELD 



ET 



FN 



FT 



EX 



RC 



DM 



NR 



FCB POSITIONS 

0 

1-8 

9-11 

12 

13-14 
15 

16-31 

32 



PURPOSE 

Entry type (currently not used, 
but assumed zero) 

File name, padded with ASCII 
blanks 

File type, padded with ASCII 
blanks 

File extent, normally set to 
zero 

Not used, but assumed zero 

Record count is current extent 
Size (0 to 128 records) 

Disk allocation map, filled-in 
and used by CP/M 

Next record number to read or 
write 
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3.3 Disk Access Primitives 

Given that a program has properly initialized the FCB's for 
each of its files, there are several operations which can be per- 
formed, as shown in Table II. In each case, the operation is 
applied to the currently selected disk (see the disk select oper- 
ation in Table II), using the file information in a specific FCB, 
The following PL/M program segment, for example, copies the con- 
tents of the file X.Y to the (new) file NEW. FIL: 

DECLARE RET BYTE..; 

OPEN: PROCEDURE (A) 

DECLARE A ADD&ESS; 
RET=MON2(15,A) ; 
END OPEN; 

CLOSE: PROCEDURE (A); 

DECLARE A ADDRESS; 
RET=MON2(16,A) ; 
END; 



MAKE 



PROCEDURE (A) ; 
DECLARE A ADDRESS; 
RET=M0N2 (22 , A) ; 
END MAKE; 



DELETE: PROCEDURE (A); 

DECLARE A ADDRESS ; 

/* IGNORE RETURNED VALUE */ 

CALL MONl(19,A) ; 

END DELETE; 

RE A DBF : PROCEDURE (A) ; 

DECLARE A ADDRESS; 
RET=MON2(20,A) ; 
END RE A DBF ; 

WRITEBF: PROCEDURE (A); 

DECLARE A ADDRESS; 
RET=MON2(21,A) ; 
END WRITEBF; 



INIT: PROCEDURE; 

CALL MON1(13,0) ; 

END INIT; 

/* SET UP FILE CONTROL BLOCKS */ 
DECLARE FCB1 (33) BYTE 

INITIAL (0,*X ','Y ',0,0,0,0), 

FCB2 (33) BYTE 

INITIAL (0, 'NEW ' , ' FIL' ,0,0,0,0) ; 



CALL INIT; 

/* ERASE 'NEW. FIL 1 IF IT EXISTS */ 
CALL DELETE (.FCB2); 

/* CREATE 1 'NEW. FIL' AND CHECK SUCCESS */ 
CALL MAKE ( . FCB2 ) ; 

IF RET = 255 THEN CALL PRINT (.'NO DIRECTORY SPACE $'); 
ELSE 

DO; /* FILE SUCCESSFULLY CREATED, NOW OPEN 'X.Y' */ 
CALL OPEN (.FCB1) ; 

IF RET = 255 THEN CALL PRINT (.'FILE NOT PRESENT $*); 
ELSE 

DO; /* FILE X.Y FOUND AND OPENED, SET 
NEXT RECORD TO ZERO FOR BOTH FILES */ 
FCB1 ( 32) , FCB2(32) = 0; 

/* READ FILE X.Y UNTIL EOF OR ERROR */ 
CALL READBF (.FCB1); /*READ TO 80H*/ 
DO WHILE RET = 0 ; 

CALL WRITEBF ( . FCB2) /*WRITE FROM 80H*/ 
IF RET = 0 THEN /*GET ANOTHER RECORD*/ 

CALL READBF (.FCB1); ELSE 

CALL PRINT (. 'DISK WRITE ERROR $') ; 
END; 

IF RET < >1 THEN CALL PRINT (.' TRANSFER ERROR $'); 
ELSE 

DO; CALL CLOSE (. FCB2) ; 

IF RET = 255 THEN CALL PRINT (.'CLOSE ERROR$ ' ) ; 
END; 
END; 
END; 

EOF 

This program consists of a number of utility procedures for 
opening, closing, creating, and deleting files, as well as two 
procedures for reading and writing data. These utility procedures 
are followed by two FCB's for the input and output files. In 
both cases, the first 16 bytes are initialized to the <filename> 
and < filetype> of the input and output files. The main program 
first initializes the disk system, then deletes any existing 
copy of "NEW. FIL" before starting. The next step is to create 
a new directory entry (and empty file) for "NEW. FIL". If file 
creation is successful, the input file "X.Y" is opened. If this 
second operation is also successful, then the disk to disk copy 
can proceed. The NR fields are set to zero so that the first 
record of each file is accessed on subsequent disk I/O operations. 
The first call to READBF fills the (implied) DMA buffer at 80H 
with the first record from X.Y. The loop which follows copies 
the record at 80H to "NEW. FIL" and then reports any errors, or 
reads another 128 bytes from X.Y. This transfer operation con- 
tinues until either all data has been transferred, or an error 
condition arises. If an error occurs, it is reported; other- 
wise the new file is closed and the program halts. 



TABLE II 





DISK ACCESS 


PRIMITIVES 




FUNCTION/NUMBER 


ENTRY PARAMETERS 


RETURNED VALUE 


TYPICAL CALL 


Lift Head 
12 


None 


None 

Head is lifted from 
current drive 


CALL MON2(12,0) 


Initialize BDOS 
and select disk 
"A" 

Set DMA address 
to 8 OH 

13 


None 


None 

Side effect is that 
disk A is "logged- 
in" while all others 
are considered "off- 
line" 


CALL MON1(13,0) 


Log— in and 
select disk 
X 

14 


An integer value cor- 
responding to the 
disk to log -in: 
A=0, B=l , C=2 , etc. 


None 

Disk X is considered 
"on-line" and selec- 
ted for subsequent 
file operations 


CALL MONl(14,l) 
(log-in disk "B") 


Open file 
15 


Address of the FCB 
tor tne rile to be 
accessed 


Byte address of the 
FCB in the directory, 
if found, or 255 if 
file not present. 
The DM bytes are set 
by the BDOS. 


I = MON2(15,.FCB) 


Close file 


Address of an FCB 
which has been pre- 
viously created or 
opened 


Byte address of the 
directory entry cor- 
responding to the 
FCB, or 255 if not 
present 


I = M0N2 (16, .FCB) 
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TABLE II (continued) 



FUNCTION/NUMBER 



ENTRY PARAMETERS 



RETURNED VALUE 



TYPICAL CALL 



Search for file 
17 



Address of FCB con- 
taining <filename> 
and <filetype> to 
match. ASCII "?" 
in FCB matches any 
character . 



Byte address of first 
FCB in directory that 
matches input FCB, if 
any; otherwise 255 
indicates no match. 



I = M0N2 (17, .FCB) 



Search for next 
occurrence 

18 



Same as above, but 
called after func- 
tion 17 (no other 
intermediate BDOS 
calls allowed) 



Byte address of next 



I = M0N2 (18, .FCB) 



Delete File Address of FCB con- None I = M0N2 (19, .FCB) 

1 q taining <f ilename> 

and <filetype> of 
file to delete from 
diskette 



Read Next Record 
20 



Address of FCB of a 
successfully OPENed 
file, with NR set 
to the next record 
to read (see note^) 



0 = successful read 

1 = read past end of 

file 

2 = reading unwritten 

data in random 
access 



I = M0N2 (20, .FCB) 



Note, : The I/O operations transfer data to/from address 80H for the next 12 8 bytes unless 
the DMA address has been altered (see function 26) . Further, the NR field of the 
FCB is automatically incremented after the operation. If the NR field exceeds 128, 
the next extent is opened automatically, and the NR field is reset to zero. 
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TABLE II (continued) 



FUNCTION/NUMBER ENTRY PARAMETERS RETURNED VALUE TYPICAL CALL 



Write Next Record 


Same as above, except 


0 = successful write 


I 


= M0N2 (21, 


.FCB) 


21 


NR is set to the next 


1 = error in extend- 








record to write 


ing file 
2 = end of disk data 
255 = no more dir- 
ectory space 

(see note-) 
2 








Make File 


Address of FCB with 


Byte address of dir- 


I 




• r CB) 


22 


<filename> and < file- 


ectory entry alloca- 








type > set. Direc- 
tory entry is cre- 
ated, the file is 
initialized to empty. 


ted to the FCB, or 
255 if no directory 
space is available 








Rename FCB 


Address of FCB with 
old FN and FT in 


Address of the dir- 
ectory entry which 


I 


= M0N2 (2 3, 


.FCB) 


23 


first 16 bytes, and 
new FN and FT in 


matches the first 
16 bytes. The 










second 16 bytes 


<f ilename>and < file- 










type > is altered 
255 if no match. 









Note 2 : There are normally 64 directory entries available on each diskette (can be 
expanded to 255 entries), where one entry is required for the primary file, 
and one for each additional extent. 
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TABLE II (continued) 



FUNCTION/NUMBER 



ENTRY PARAMETERS 



RETURNED VALUE 



TYPICAL CALL 



Interrogate log- 
in vector 

24 



None 



Byte value with "1" 
in bit positions of 
"on line" disks, 
with least signi- 
ficant bit corres- 
ponding to disk "A" 



I = M0N2 (2 4,0 



Set DMA address 
26 



Address of 12 8 byte 
DMA buffer 



None 

Subsequent disk I/O 
takes place at spe- 
cified address in 
memory 



CALL MON1 (26,2000H) 



Interrogate 
Allocation 

27 



None 



Address of the allo- 
cation vector for 
the current disk 
(usedby STATUS com- 
mand) 



MON3: PROCEDURE (... ) 
ADDRESS; 

A = MON3(27,0) ; 



Interrogate Drive 
number 

25 



None 



Disk number of currently 
logged disk (i.e., the 
drive which will be used 
for the next disk operation 



I = MON2(25,0) ; 
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3.4 Random Access 

Recall that a single FCB describes up to a 16K segment of a 
(possibly) larger file. Random access within the first 16K seg- 
ment is accomplished by setting the NR field to the record number 
of the record to be accessed before the disk I/O takes place. 
Note, however, that if the 128th record is written, then the 
BDOS automatically increments the extent field (EX), and opens 
the next extent, if possible. In this case, the program must 
explicitly decrement the EX field and re-open the previous extent. 
If random access outside the first 16K segment is necessary, 
then the extent number e be explicitly computed, given an absol- 
ute record number r as 

or equivalently , 

e = SHR ( r , 7 ) 

this extent number is then placed in the EX field before the seg- 
ment is opened. The NR value n is then computed as 

n = r mod 128 

or 

n = r AND 7FH. 

When the programmer expects considerable cross-segment accesses, 
it may save time to create an FCB for each of the 16K segments, 
open all segments for access, and compute the relevant FCB from 
the absolute record number r. 



4. SYSTEM GENERATION 

As mentioned previously, every diskette used under CP/M is assumed to 
contain the entire system (excluding transient commands) on the first two 
tracks. The operating system need not be present, however, if the diskette 
is only used as secondary disk storage on drives B, C, since the CP/M 

system is loaded only from drive A. 

The CP/M file system is organized so that an IBM-compatible diskette 
from the factory (or from a vendor which claims IBM compatibility) looks 
like a diskette with an empty directory. Thus, the user must first copy 
a version of the CP/M system from an existing diskette to the first two 
tracks of the new diskette, followed by a sequence of copy operations, 
using PIP, which transfer the transient command files from the original 
diskette to the new diskette. 



19 



NOTE: before you begin the CP/M copy operation, read your Licensing 
Agreement. It gives your exact legal obligations when making reproductions 
of CP/M in whole or in part, and specifically requires that you place the 
copyright notice 

Copyright (c) , 1976 
Digital Research 

on each diskette which results from the copy operation. 
4.1. Initializing CP/M from an Existing Diskette 

The first two tracks are placed on a new diskette by running the tran- 
sient command SYSGEN, as described in the document "An Introduction to CP/M 
Features and Facilities." The SYSGEN operation brings the CP/M system from 
an initialized diskette into memory, and then takes the memory image and 
places it on the new diskette. 

Upon completion of the SYSGEN operation, place the original diskette 
on drive A, and the initialized diskette on drive B. Reboot the system; 
the response should be 

A> 

indicating that drive A is active. Log into drive B by typing 

B: 

and CP/M should respond with 

B > 

indicating that drive B is active. If the diskette in drive B is factory 
fresh, it will contain an empty directory. Non-standard diskettes may, 
however, appear as full directories to CP/M, which can be emptied by typing 

ERA * . *^ 

when the diskette to be initialized is active. Do not give the ERA command 
if you wish to preserve files on the new diskette since all files will be 
erased with this command. 

After examining disk B, reboot the CP/M system and return to drive A for 
further operations. 

The transient commands are then copied from drive A to drive B using the 
PIP program. The sequence of commands shown below, for example, copy the 
principal programs from a standard CP/M diskette to the new diskette: 

A>PIP, 

*B : STAT . COM=STAT . COM^ 
*B :PIP .COM=PIP .COMp 
*B : LOAD . COM=LOAD . COMp 
*B : ED . COM=ED . COM> 
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*B : ASM . COM-ASM. COMp 

*B : SYSGEN . COM=SYSGEN . COM 

*B:DDT.COM«DDT.COM> * 

V 

A> 



The user should then log in disk B, and type the command 
DIR *.* J? 

to ensure that the files were transferred to drive B from drive A. The 
various programs can then be tested on drive B to check that they were 
transferred properly. 

Note that the copy operation can be simplified somewhat by creating 
a " submit" file which contains the copy commands. The file could be 
named GEN. SUB, for example, and might contain 



SYSGEN, 

PIP B: STAT. COM«STAT. COM, 

PIP BrPIP.COM-PIP.COM^ 

PIP B:LOAD.COM«LOAD.COM, 

PIP B : ED. COMBED. COM y 

PIP B:ASM.COM=ASM.COfy 

PIP B: SYSGEN. COM=SYSGEN . COM^ 

PIP B:DDT.COM«DDT.COM, 

The generation of a new diskette from the standard diskette is then done 
by typing simply 

SUBMIT GEN, 



5. CP/M ENTRY POINT SUMMARY 

The functions shown below summarize the functions of the 
FDOS. The function number is passed in Register C (first para- 
meter in PL/M) , and the information is passed in Registers D,E 
(second PL/M parameter) . Single byte results are returned in 
Register A. If a double byte result is returned, then the high 
order byte comes back in Register B (normal PL/M return) . The 
transient program enters the FDOS through location "entry" (see 
Section 7.) as shown in Section 2. for PL/M, or 



CALL entry 



in assembly language. All registers are altered in the FDOS. 
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Function Number Information Result 

0 System Reset 

1 Read Console ASCII character 

2 Write Console ASCII character 

3 Read Reader ASCII character 

4 Write Punch ASCII character 

5 Write List ASCII character 

6 (not used) 

7 Interrogate I/O Status I/O Status Byte 

8 Alter I/O Status I/O Status Byte 

9 Print Console Buffer Buffer Address 

10 Read Console Buffer Buffer Address 

11 Check Console Status True if characte: 

Ready 

12 Lift Disk Head 

13 Reset Disk System 

14 Select Disk Disk number 

15 Open File FCB Address Completion Code 

16 Close File " 

17 Search First " " " " 

18 Search Next " « • •• 

19 Delete File " " " " 

20 Read Record " " " " 

21 Write Record " " " " 

22 Create File " " " " 

23 Rename File " •» » 

24 Interrogate Login Login Vector 

25 Interrogate Disk - Selected Disk 

Number 

26 Set DMA Address DMA Address 

27 Interrogate Allocation Address of Allo- 

cation Vector 
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6. ADDRESS ASSIGNMENTS 

The standard distribution version of CP/M is organized for an Intel 
MDS microcomputer developmental system with 16K of main memory, and two 
diskette drives. Larger systems are available in 16K increments, providing 
management of 32K, 48K, and 64K systems (the largest MDS system is 62K 
since the ROM monitor provided with the MDS resides in the top 2K of the 
memory space) . For each additional 16K increment, add 4000H to the values 
of cbase and fbase. 

The address assignments are 



boot = 0000H 
tfcb = 005CH 
tbuff* 0080H 
tbase= 0100H 
cbase= 2900H 
fbase* 3200H 
entry* 0005H 



warm start operation 

default file control block location 

default buffer location 

base of transient program area 

base of console command processor 

base of disk operating system 

entry point to disk system from 

user programs 



7. SAMPLE PROGRAMS 



This section contains two sample programs which interface with the CP/M 
operating system. The first program is written in assembly language, and 
is the source program for the DUMP utility. The second program is the CP/M 
LOAD utility, written in PL/M. 

The assembly language program begins with a number of "equates" for sys- 
tem entry points and program constants. The equate 

BDOS EQU 0005H 

for example, gives the CP/M entry point for peripheral I/O functions. The 
defualt file control block address is also defined (FCB) , along with the 
default buffer address (BUFF) . Note that the program is set up to run at 
location 100H, which is the base of the transient program area. The stack 
is first set-up by saving the entry stack pointer into OLDSP, and resetting 
SP to the local stack. The stack pointer upon entry belongs to the console 
command processor, and need not be saved unless control is to return to the 
CCP upon exit. That is, if the program terminates with a reboot (branch to 
location 0000H) then the entry stack pointer need not be saved. 

The program then jumps to MAIN, past a number of subroutines which are 
listed below: 

BREAK - when called, checks to see if there is a console 

character ready. BREAK is used to stop the listing 
at the console 

PCHAR - print the character which is in register A at the 
console . 

CRLF - send carriage return and line feed to the console 

PNIB - print the hexadecimal value in register A in ASCII 
at the console 

PHEX - print the byte value (two ASCII characters) in 
register A at the console 

ERR - print error flag #n at the console , where n is 

1 if file cannot be opened 

2 if disk read error occurred 

GNB - get next byte of data from the input file. If the 
IBP (input buffer pointer) exceeds the size of the 
input buffer, then another disk record of 128 bytes 
is read. Otherwise, the next character in the buffer 
is returned. IBP is updated to point to the next 
character. 
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The MAIN program then appears, which begins by calling SETUP. The SETUP 
subroutine, discussed below, opens the input file and checks for errors. 
If the file is opened properly, the GLOOP (get loop) label gets control. 

On each successive pass through the GLOOP label, the next data byte 
is fetched using GNB and save in register B. The line addresses are listed 
every sixteen bytes, so there must be a check to see if the least signi- 
ficant 4 bits is zero on each output. If so, the line address is taken 
from registers h and 1, and typed at the left of the line. In all cases, 
the byte which was previously saved in register B is brought back to 
register A, following label NONUM, and printed in the output line. The 
cycle through GLOOP continues until an end of file condition is detected 
in DISKR, as described below. Thus, the output lines appear as 

0000 bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb 
0010 bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb 



until the end of file. 

The label FINIS gets control upon end of file. CRLF is called first 
to return the carriage from the last line output. The CCP stack pointer 
is then reclaimed from OLDSP, followed by a RET to return to the console 
command processor. Note that a JMP 0000H could be used following the 
FINIS label, which would cause the CP/M system to be brought in again from 
the diskette (this operation is necessary only if the CCP has been over- 
layed by data areas) . 

The file control block format is then listed (FCBDN ... FCBLN) which 
overlays the fcb at location 05CH which is setup by the CCP when the 
DUMP program is initiated. That is, if the user types 

DUMP X.Y 

then the CCP sets up a properly formed fcb at location 05CH for the DUMP 
(or any other) program when it goes into execution. Thus, the SETUP sub- 
routine simply addresses this default fcb, and calls the disk system to 
open it. The DISKR (disk read) routine is called whenever GNB needs another 
buffer full of data. The default buffer at location 80H is used, along 
with a pointer (IBP) which counts bytes as they are processed. Normally, 
an end of file condition is taken as either an ASCII 1AH (control-z) , or 
an end of file detection by the DOS. The file dump program, however, stops 
only on a DOS end of file. 



FILE DUMP PROGRAM, READS AN INPUT FILE AND PRINTS IN 1 



COPYRIGHT (C) , DIGITAL RESEARCH , 1975, 1976 



25 



n i oi n 






UKCj 


i ex oi i3 


0005 


= 


BDOS 


EQU 


0005H ;D0S ENTRY POINT 


000F 


= 


OPENF 


EQU 


15 ?FILE OPEN 


0014 




KLADb 


con 


O 01 .DC A. TV CnKI/Tp TOM 


fx n ot *"> 
0002 




rp V TIC C 


con 


O .TV DC* CfTMPT'THM 


(a n cii i 




LUNo 


con 


i •dc An rnwcnr c 

1 ' siCttru V^UlNoUijIj 


^ oi 01 d 




n o v c 




11 ,DDPAV IfCV PTTMP'T'TOKI /TPHF TP PWAP. PFA 
11 } DKCiftft l\tj I r UWLI J.ULN vlr<Un> If V^n.HJtx Jt\Eirt 


W 10 OL. 




? 

r 


con 


DL»n Jc xLiCt VAJtMlrvULj DliUClX HUUKdOO 


ft ft Q ft 




dUcc 

• 


EQU 


80H ; INPUT DISK BUFFER ADDRESS 






1 

• 


SET UP 


STACK 


0100 


210 00 0 




LXI 


H r 0 


0103 


39 




DAD 


SP 


0104 


220r 01 




SHLD 


OLDSP 


0107 


315101 




LXI 


SP, STKTOP 


010A 


C3C401 




JMP 


MAIN 






• 


VARIABLES 


010D 




IBP: 


DS 


2 ; INPUT BUFFER POINTER 






t 

m 


STACK AREA 


k3 JL lor 




OLDSP: 


DS 


2 


KJ 1 1 1 




STACK: 


DS 


64 


10 J. D 1 




STKTOP EQU 


$ 








SUBROUTINES 






BREAK : 


;CHECK 


BREAK KEY (ACTUALLY ANY KEY WILL DO) 


01 1 C 1 


pen cp c 




PUSH H! 


PUSH D! PUSH B; ENVIRONMENT SAVED 


fill C J| 

10 1 D4 


nri (in 




MVI 


CBRKF 


01 DO 


CD0O00 




CALL 


BDOS 


(IT CA 

01 by 


LIDILI 




POP B! 


POP D! POP H; ENVIRONMENT RESTORED 


015C 


C9 




RET 








• 

PCHAR: 


; PRINT 


A CHARACTER 


ill rr\ 

01 5D 


tT' c r\ c o c 




PUSH H! 


PUSH D! PUSH B; SAVED 


men 


oi c oi o 




MVI 


CTYPEF 


oi i a "> 


Dr 




MOV 


E,A 


Bib j 


r* oi c: (a a 




CALL 


BDOS 


0166 


C1D1E1 




POP B! 


POP D! POP H; RESTORED 


01 1 C Q 




• 


RET 








CRLF: 






(71 1 £ A 
1(5 1 DA 


O C fX T> 




MVI 


A, 0DH 


fcjl oL 


LDbD01 




CALL 


PCHAR 


016F 


3E0A 




MVI 


A, 0AH 


0171 


CD5D01 




CALL 


PCHAR 


0174 


C9 


• 


RET 








• 

PNIB: 


; PRINT 


NIBBLE IN REG A 


0175 


E60F 




AN I 


0FH ;L0W 4 BITS 


0177 


FE0A 




CPI 


.10 


0179 


D28101 




JNC 


P10 



017C C630 
017E C38301 



LESS THAN OR EQUAL TO 9 
AD I '0' 
JMP PRN 







• 

9 


GREATER 


OR EQUAL TO 10 


0181 


C637 


P10: 


AD I 


'A' - 10 


0183 


CD5D01 


PRN: 


CALL 


PCHAR 


0186 


C9 


• 


RET 








9 

PHEX: 


; PRINT 


HEX CHAR IN REG 


0187 


F5 




PUSH 


PSW 


0188 


0F 




RRC 




0189 


0F 




RRC 




018A 


0F 




RRC 




018B 


0F 




RRC 




018C 


CD7501 




CALL 


PNIB ; PRINT 


018F 


Fl 




POP 


PSW 


0190 


CD7501 




CALL 


PNIB 


0193 


C9 




RET 








• 

9 

ERR: 


; PRINT 


ERROR MESSAGE 


0194 


CD6A01 




CALL 


CRLF 


0197 


3E23 




MVI 


A, '# ' 


0199 


CD5D01 




CALL 


PCHAR 


019C 


78 




MOV 


A, B 


019D 


C630 




AD I 


'0' 


019F 


CD5D01 




CALL 


PCHAR 


01A2 


CD6A01 




CALL 


CRLF 


01A5 


C3F701 


• 


JMP 


FINIS 






GNB: 


;GET NEXT BYTE 


01A8 


3A0D01 




LDA 


IBP 


01AB 


FE80 




CPI 


80H 


01AD 


C2B401 




JNZ 


G0 








READ ANOTHER BUFFER 



01B0 CD1602 
01B3 AF 



CALL 
XRA 



DISKR 
A 



01B4 5F 
01B5 1600 
01B7 3C 
01B8 320D01 



01BB E5 
01BC 218000 
01BF 19 
01C0 7E 



01C1 El 
01C2 23 
01C3 C9 



G0: ;READ THE BYTE AT BUFF+REG A 

MOV E r A 

MVI D,0 

INR A 

STA IBP 
; POINTER IS INCREMENTED 

: SAVE THE CURRENT FILE ADDRESS 



PUSH 
LXI 
DAD 
MOV 



H 

H,BUFF 
D 

A, M 



BYTE IS IN THE ACCUMULATOR 

RESTORE FILE ADDRESS AND INCREMENT 
POP H 
INX H 
RET 



01C4 CDFF01 



MAIN: ; READ AND PRINT SUCCESSIVE BUFFERS 
CALL SETUP ?SET UP INPUT FILE 



01C7 3E80 
01C9 320D01 
01CC 21FFFF 



01CF CDA801 
01D2 47 



GLOOP: 



MVI A,80H 

STA IBP ; SET BUFFER POINTER TO 80H 

LXI H, 0FFFFH ;SET TO -1 TO START 



CALL GNB 
MOV B , A 
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PRINT HEX VALUES 



01D3 7D 
01D4 E60F 
01D6 C2EB01 

01D9 CD6A01 



CHECK FOR LINE FOLD 
MOV A, L 

ANI 0FH ;CHECK LOW 4 BITS 

JNZ NONUM 
PRINT LINE NUMBER 
CALL CRLF 



01DC CD5101 
01DF 0F 
01E0 DAF701 

01E3 7C 

01E4 CD8701 

01E7 7D 

01E8 CD8701 

01EB 3E20 
01ED CD5D01 
01F0 78 
01F1 CD8701 



NONUM: 



CHECK FOR BREAK KEY 

CALL BREAK 

RRC 

JC FINIS ;DON'T PRINT ANY MORE 



MOV 
CALL 
MOV 
CALL 

MVI 
CALL 
MOV 
CALL 



A,H 
PHEX 
A , L 
PHEX 

A,' ' 

PCHAR 
A, B 
PHEX 



01F4 C3CF01 



01F7 CD6A01 
01FA 2A0F01 
01FD F9 
01FE C9 



005C 
005D 
0065 
0068 
006B 
007C 
007D 



EPS A: 
FINIS 



FCBDN 
FCBFN 
FCBFT 
FCBRL 
FCBRC 
FCBCR 
FCBLN 



JMP GLOOP 
; END PSA 



CALL 
LHLD 
SPHL 
RET 



END OF INPUT 

CRLF 
OLDSP 



FILE CONTROL BLOCK DEFINITIONS 



EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 



FCB+0 

FCB+1 

FCB+9 

FCB+1 2 

FCB+15 

FCB+32 

FCB+33 



DISK NAME 
FILE NAME 

DISK FILE TYPE (3 CHARACTERS) 
FILE'S CURRENT REEL NUMBER 
FILE'S RECORD COUNT (0 TO 128) 
CURRENT (NEXT) RECORD NUMBER (0 TO ] 
FCB LENGTH 



01FF 115C00 
0202 0E0F 
0204 CD0500 



0207 
0209 



FEFF 
C21102 



SETUP: ;SET UP FILE 

; OPEN THE FILE FOR INPUT 

LXI D , FCB 

MVI COPENF 

CALL BDOS 
; CHECK FOR ERRORS 

CPI 255 

JNZ OPNOK 



BAD OPEN 





0001 




MT7T 
MVI 


B r 1 


;UrtiN 1 


n o a x? 


/T\ Q >i til i 
LD 9 4101 




CALL 


ERR 








OPNOK : 


;0PEN 


IS OK. 




0211 


AF 




XRA 


A 




moil 
0212 


j27C00 




STA 


FCBCR 




n o 1 c 

0215 


C9 


• 


RET 










DISKR: 


; READ 


DISK FILE 


t\ rt f\ /"\ r\ t\ 

RECORD 


0216 


E5D5C5 




PUSH HI PUSH Dl 


PUSH B 








T V T 


D,FCB 




W Z 1L 






MVI 


C , READF 




0 21E 


LD0D00 




CALL 


BDOS 






LlUlhl 




POP B! 


POP D! POP H 


0224 


n> n> flt fit 




CPI 


0 


?CHECK 


0226 


C8 




RZ 










• 


MAY BE 


EOF 




Idzz / 






CPI 


1 




0229 


CAF701 


• 


JZ 


FINIS 




HOOP 


0 602 




MVI 


B,2 


jDISK 


022E 


CD9401 


• 


CALL 


ERR 




0231 






END 







The PL/M program which follows implements the CP/M LOAD utility. The 
function is as follows. The user types 



LOAD filename^ 

If filename. HEX exists on the diskette, then the LOAD utility reads the "hex" 
formatted machine code file and produces the file 

filename.COM 

where the COM file contains an absolute memory image of the machine code, 
ready for load and execution in the TPA. If the file does not appear on 
the diskette, the LOAD program types 

SOURCE IS READER 

and reads an Addmaster paper tape reader which contains the hex file. 

The LOAD program is set up to load and run in the TPA, and, upon com- 
pletion, return to the CCP without rebooting the system. Thus, the pro- 
gram is constructed as a single procedure called LOADCOM which takes the 
form 



OFAH: 

LOADCOM: PROCEDURE; 
/" /* LIBRARY PROCEDURES */ 
M0N1 : . . . 

/* END LIBRARY PROCEDURES */ 
MOVE : . . . 
GETCHAR: ... 
PRINTNIB: . . . 
PRINT HEX: ... 
PRINTADDR: ... 
RELOC : ... 
SETMEM: 
READHEX: 
READBYTE : 
READCS : 
MAKE DOUBLE : 
DIAGNOSE: 
^END RELOC; 

DECLARE STACK (16) ADDRESS, SP ADDRESS; 
SP = STACKPTR; STACKPTR * . STACK (LENGTH (STACK) ) ; 



CALL RELOC; 

• • • 

STACKPTR * SP; 
V RETURN 0; 
END LOADCOM; 



EOF 
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The label OF AH at the beginning sets the origin of the compilation to OF AH, 
which causes the first 6 bytes of the compilation to be ignored when loaded 
(i.e., the TPA starts at location 100H and thus OFAH , . . . , OFFH are deleted 
from the COM file). In a PL/M compilation, these 6 bytes are used to set up 
the stack pointer and branch around the subroutines in the program. In, this 
case, there is only one subroutine, called LOADCOM, which results in the 
following machine memory image for LOAD 

OFAH: LXI SP,plmstack ;SET SP TO DEFAULT STACK 

OFDH: JMP pastsubr ; JUMP AROUND LOADCOM 

100H: beginning of LOADCOM procedure 

• • * • 

end of LOADCOM procedure 
RET 

pastsubr: 
EI 
HLT 

Since the machine code between OFAH and OFFH is deleted in the load, 
execution actually begins at the top of LOADCOM. Note, however, that 
the initialization of the SP to the default stack has also been deleted; 
thus, there is a declaration and initialization of an explicit stack and 
stack pointer before the call to RELOC at the end of LOADCOM. This is 
necessary only if we wish t6 return to the CCP without a reboot operation: 
otherwise the origin of the program is set to 100H, the declaration of 
LOADCOM as a procedure is not necessary, and termination is accomplished 
by simply executing a 

GO TO OOOOH; 

at the end of the program. Note also that the overhead for a system re- 
boot is not great (approximately 2 seconds) , but can be bothersome for 
system utilities which are used quite often, and do not need the extra 
space. 

The procedures listed in LOADCOM as "library procedures" are a standard 
set of PL/M subroutines which are useful for CP/M interface. The RELOC 
procedure contains several nested subroutines for local functions, and 
actually performs the load operation when called from LOADCOM. Control 
initially starts on line 327 where the stackpointer is saved and re- initialized 
to the local stack. The default file control block name is copied to 
another file control blocJc (SFCB) since two files may be open at the same 
time. The program then calls SEARCH to see if the HEX file exists; if not, 
then the high speed reader is used. If the file does exist, it is opened for 
input (if possible) . The filetype COM is moved to the default file control 
block area, and any existing copies of filename.COM files are removed from 
the diskette before creating a new file. The MAKE operation creates a new 
file, and, if successful, RELOC is called to read the HEX file and produce 
the COM file. At the end of processing by RELOC, the COM file is closed 
(line 350) . Note that the HEX file does not need to be closed since it 
was opened for input only. The data written to a file is not permanently 
recorded until the file is successfully closed. 
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Disk input characters are read through the procedure GETCHAR on line 
137. Although the DMA facilities of CP/M could be used here, the GETCHAR 
procedure instead uses the default buffer at location 80H and moves each 
buffer into a vector called SBUFF (source buffer) as it is read. On exit, 
the GETCHAR procedure returns the next input character and updates the 
source buffer pointer (SBP) . 

The SETMEM procedure on line 191 performs the opposite function from 
GETCHAR. The SETMEM procedure maintains a buffer of loaded machine code 
in pure binary form which acts as a "window" on the loaded code. If there 
is an attempt by RELOC to write below this window, then the data is ignored. 
If the data is within the window, then it is placed into MBUFF (memory 
buffer) . If the data is to be placed above this window, then the window 
is moved up to the point where it would include the data address by writing 
the memory image successively (by 128 byte buffers), and moving the base 
address of the window. Using this technique, the programmer can recover 
from checksum errors on the high-speed reader by stopping the reader, 
rewinding the tape for some distance, then restarting LOAD (in this case, 
LOADing is resumed by interrupting with a NOP instruction) . Again, the 
SETMEM procedure uses the default buffer at location 80H to perform the 
disk output by moving 128 byte segments to 80H through OFFH before each 
write. 
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0FAH: DECLARE BDOS LITERALLY '0005H'; 
/* TRANSIENT COMMAND LOADER PROGRAM 

COPYRIGHT (C) DIGITAL RESEARCH 
JUNE, 1975 

V 

LOADCOM: PROCEDURE BYTE; 

DECLARE FCBA ADDRESS INITIAL ( 5CH) ; 
DECLARE FCB BASED FCBA (33) BYTE; 

DECLARE BUFFA ADDRESS INITIAL ( 80H) , /* I/O BUFFER ADDR 

BUFFER BASED BUFFA (128) BYTE; 

DECLARE SFCB(33) BYTE, /* SOURCE FILE CONTROL BLOCK * 

BSIZE LITERALLY '1024', 
EOFILE LITERALLY ' 1AH ' , 

SBUFF (BSIZE) BYTE /* SOURCE FILE BUFFER */ 

INITIAL (EOFILE) , 
RFLAG BYTE, /* READER FLAG */ 

SBP ADDRESS; /* SOURCE FILE BUFFER POINTER 

/* LOADCOM LOADS TRANSIENT COMMAND FILES TO THE DISK F 
CURRENTLY DEFINED READER PERIPHERAL. THE LOADER PLACE 
CODE INTO A FILE WHICH APPEARS IN THE LOADCOM COMMAND 
/* **************** LIBRARY PROCEDURES FOR DISKIO ******* 



MON1: PROCEDURE (F, A) ; 
DECLARE F BYTE, 
A ADDRESS; 
GO TO BDOS; 
END MON1; 

MON2: PROCEDURE (F, A) BYTE; 
DECLARE F BYTE, 
A ADDRESS; 
GO TO BDOS; 
END MON2; 

READRDR: PROCEDURE BYTE; 

/* READ CURRENT READER DEVICE */ 
RETURN MON2(3,0) ; 
END READRDR; 

DECLARE 

TRUE LITERALLY '1', 

FALSE LITERALLY '0', 

FOREVER LITERALLY 'WHILE TRUE', 

CR LITERALLY '13', 
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LF LITERALLY '10' r 
WHAT LITERALLY '63'? 

PRINTCHAR: PROCEDURE (CHAR) ; 33 
DECLARE CHAR BYTE; 
CALL M0N1 (2,CHAR) ; 
END PRINTCHAR; 

CRLF: PROCEDURE; 

CALL PRINTCHAR (CR) ; 
CALL PRINTCHAR ( LF ) ; 
END CRLF; 

PRINT: PROCEDURE (A) ; 

DECLARE A ADDRESS; 

/* PRINT THE STRING STARTING AT ADDRESS A UNTIL THE 
NEXT DOLLAR SIGN IS ENCOUNTERED */ 
CALL CRLF; 
CALL M0N1 (9, A) ; 
END PRINT; 

DECLARE DCNT BYTE; 

INITIALIZE: PROCEDURE; 
CALL M0N1 (13,0) ; 
END INITIALIZE; 

SELECT: PROCEDURE (D) ; 
DECLARE D BYTE; 
CALL MONK 14, D) ; 
END SELECT; 

OPEN: PROCEDURE (FCB) ; 

DECLARE FCB ADDRESS; 
DCNT = MON2(15,FCB) ; 
END OPEN; 

CLOSE: PROCEDURE (FCB) ; 

DECLARE FCB ADDRESS; 
DCNT = MON2(16,FCB) ; 
END CLOSE; 

SEARCH: PROCEDURE ( FCB) ; 
DECLARE FCB ADDRESS; 
DCNT = MON2(17,FCB) ; 
END SEARCH; 

SEARCHN: PROCEDURE; 

DCNT = MON2(18,0) ; 
END SEARCHN; 

DELETE: PROCEDURE ( FCB) ; 
DECLARE FCB ADDRESS; 
CALL MON1 (19, FCB) ; 
END DELETE; 

DISKREAD: PROCEDURE ( FCB) BYTE; 
DECLARE FCB ADDRESS; 
RETURN MON2(20,FCB) ; 
END DISKREAD; 
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DISKWRITE: PROCEDURE f PC B) BYTE* 
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DECLARE FCB ADDRESS: 
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RETURN M0N2 (21 ,FCB) ; 34 
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END DISKWRITE: 
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MAKE* PROCEDURE 1 FCB) • 
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DECLARE PCR, AnDRPQC. 
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DCNT = MON2 ( 22 .FCB) : 
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END MAKE • 

XJ 4-^ JUS & X4» XV XJ J> 
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2 
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RENAME: PROCEDURE (FCB) ; 
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DECLARE FCB ADDRESS* 

x*/xj*w jurn\u x. x/ jrxxv ui\u t»J x>j ^ 
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CALL M0N1 ( 23 .FCB) • 
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/* ******************* PMn OF LIBRARY PROCEDURES ********** 
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MOVE: PROCEDURE (S .D.N) • 

x xv-/ v xj • x. xvw\** xj xj \j x vxj y wj •> xj p x* / 
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DECLARE (S,D) ADDRESS, N BYTE, 
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A BASED S BYTE, B BASED D BYTE; 
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DO WHILE (N:=N-1) <> 255: 

X-Zw v V XX X XJ XJ ^li • 11 X / X r X> •*/ *J f 
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B ss A* S=S+1 • D=D+1 • 
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END; 
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END MOVE; 
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GETCHAR: PROCEDURE BYTE; 
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/* GET NEXT CHARACTER */ 
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DECLARE I BYTE; 
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IF RFLAG THEN RETURN READRDR; 
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IF (SBP :*= SBP+1) <= LASTfSBUFF) THEN 

X X y La* X • laJ XV x 1 X / X XJ«*XJ' X y \*J W Ui •> / X 44 A-J 
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RETURN SBUFF fSBP): 
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/* OTHERWISE READ ANOTHER BUFFER FULL */ 

/ \>/ X IX XJ XV F» X XJ XJ ; XxXJ4*X«/ frVLl \J X XX XJ XX XJ \J X JL XJ *\ X VJ XJ XJ / 


00144 
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DO SBP * 0 TO LAST (SBUFF) BY 128; 


00145 


3 


IF ( I : =DISKREAD ( .SFCB) ) = 0 THEN 
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CALL MOVE ( 80H . .SBUFF (SBP) . 80H) : ELSE 


00147 


4 


DO* IF IOl THEN CALL PRINT (.'DISK READ ER 

%j v/ f> x x x ^ x x x XX xj n Va^AA xj xj x xv x xi x y • X** «v w *% *^*— 1 * *j *^ 


ROR$ ' ) : 
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SBUFF fSBP) « EOFILE: 

IkJ 1m/ VJ 1. Jk y laJ XJ X y XJ\a/X XXJXI JP 
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SBP * LAST ( SBUFF): 

haS *-/ Ja XJJk+hmJ X y kJ 4— ' VJ X 4. / ^ 
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END; 
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END; 
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SBP as 0 • RETURN SBUFF : 
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END GETCHAR; 
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DECLARE 
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STACKPOINTER LITERALLY 'STACKPTR': 

bJ 4a * * >^ AX 4a aia ■■> 4aJ 4> » XJ X X 4hI AX4T* Xmi XJ X w X X* 1.X X X XV f 
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PRINTNIB: PROCEDURE (N) : 

4- XV al* X X^ <4> 4w/ • 4a XV \*S W XJ XJ' W XV XJ y X« J / 
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DECLARE N RYTR* 

XJ'XJVm* XJ*» XV Xj ll U 4 X U f 
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TP m > Q THEN CAT.T. PRTNTCHAR (N+ ' A "-1 0 ) • ELSE 
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CALL PRINTCHAR / N+ ' 0 ' ) • 

v»» **xj xj x xv xn i v^ xmxv ^ iiT xj J 9 


00162 


3 


END PRINTNIB; 


00163 


2 




00164 


2 


PRINTHEX: PROCEDURE (B) • 

X XV X XI X XX XJ d\ • X iWv XJ XJ vJ XV XJ y XV 1 ^ 
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DECLARE B BYTE • 

LJ XJ V*» XJf> XvXJ Xa/ XJ 14 u / 
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CALL PRINTNIB(SHR(B,4) ) ; CALL PRINTNIB (B AND 0FH) ; 


00167 


3 


END PRINTHEX; 
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PRINTADDR: PROCEDURE (A) ? 
DECLARE A ADDRESS? 

CALL PRINTHEX (HIGH (A) ) ; CALL PRINTHEX ( LOW (A) ) ? 
END PRINTADDR; 



/* INTEL HEX FORMAT LOADER */ 

RELOC: PROCEDURE? 

DECLARE (RL, CS , RT) BYTE? 
DECLARE 

LA ADDRESS*. 
TA ADDRESS , 
SA ADDRESS, 
FA ADDRESS, 
NB ADDRESS, 
SP ADDRESS, 
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/* LOAD ADDRESS */ 
/* TEMP ADDRESS */ 
/* START ADDRESS */ 
/* FINAL ADDRESS */ 
/* NUMBER OF BYTES LOADED */ 
/* STACK POINTER UPON ENTRY TO PEL 



MBUFF(256) BYTE, 

P BYTE, 

L ADDRESS? 

SETMEM: PROCEDURE (B) ? 

/* SET MBUFF TO B AT LOCATION LA MOD LENGTH (MBUFF) 

DECLARE (B,I) BYTE? 

IF LA < L THEN /* MAY BE A RETRY */ RETURN? 

DO WHILE LA > L + LAST (MBUFF) ? /* WRITE A PARA 

DO I = 0 TO 127? /* COPY INTO BUFFER */ 
BUFFER (I) = MBUFF (LOW (L) ) ? L = L + 1 ; 
END? 

./* WRITE BUFFER ONTO DISK */ 
P = P + 1? 

IF DISKWRITE (FCBA) <> 0 THEN 

DO? CALL PRINT (. 'DISK WRITE ERROR$ ') ? 
HALT ? 

/* RETRY AFTER INTERRUPT NOP */ 

L = L - 128? 

END? 

END? 

MBUFF (LOW (LA) ) = B? 
END SETMEM? 

READHEX: PROCEDURE BYTE? 

/* READ ONE HEX CHARACTER FROM THE INPUT */ 
DECLARE H BYTE? 

IF (H := GETCHAR) - '0' <= 9 THEN RETURN H - '0'? 
IF H - 'A' > 5 THEN GO TO CHARERR? 
RETURN H - 'A' + 10? 
END READHEX? 

READBYTE: PROCEDURE BYTE ? 

/* READ TWO HEX DIGITS */ 

RETURN SHL (READHEX, 4) OR READHEX? 

END READBYTE? 

READCS: PROCEDURE BYTE? 

/* READ BYTE WHILE COMPUTING CHECKSUM */ 
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DECLARE M BASED TA BYTE; 
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NEWLINE* PROCEDURE* 
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CAT.T. CRT.P • CAT.L PRINTADDR (Tk) • CALL PRINTCHAR ( ' : ' ) 
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CAT.T, PRTNT I 'ERROR ADDRESS CALL PRINTADDR ( LA^ : 
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CALL PRINT 'BYTES READ:$*1; CALL NEWLINE • 
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DO WHTT.E TA < T.A • 
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TP ^T.OWfTA^ AND 0FFH = 0 THEN CALT, NEWLINE* 
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SA, FA r NB * 0; 
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SP = STACKPOINTER? 
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P =s 0 • /* PARAGRAPH COfTNT */ 


00265 

XJ XJ \J *J 

* / 


1 


TA T.A T. ss 100H* /* P,A«?R ADDRESS OF TRANSIENT ROnTT NFS 

X n f xjt\ f xj XlWlwny / DnjjCi rtlv tyxxxj %j \JL x xvniii w X dLN X J\vu X X IN Ci %j 


/ 

00266 

U 1/ M V V 


1 


TP FAT.SF. THEN 
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CHARERR: /* ARRIVE HERE IF NON-HEX DIGIT IS ENCOU 
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/* READ RECORDS T1NTTT. *00XXXX TS FNCODNTERED */ 
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DO FOREVER: 
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/* SCAN THE : */ 
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DO WHILE GETCHAR <>';'; 
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END? 
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/* SET CHECK SUM TO ZERO, AND SAVE THE RECORD LENG 


TH */ 
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CS = 0; 
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/* MAY BE THE END OF TAPE */ 
IF (RL := READCS) = 0 THEN 
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GO TO FIN; 
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NB « NB + RL? 
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TA, LA » MAKE$DOUBLE (READCS, READCS) ; 
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IF SA * 0 THEN SA = LA; 
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/* READ THE RECORD TYPE (NOT CURRENTLY USED) */ 
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RT = READCS; 
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/* PROCESS EACH BYTE */ 
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DO WHILE (RL := RL - 1) <> 255; 
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CALL SETMEM (READCS) ; LA = LA+1 ; 
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END; 
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IF LA > FA THEN FA « LA - 1; 
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/* NOW READ CHECKSUM AND COMPARE */ 
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IF CS + READBYTE <> 0 THEN 
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DO; CALL PRINT (. 'CHECK SUM ERROR $'): 
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CALL DIAGNOSE; 
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END; 
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END; 
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FIN: 
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/* EMPTY THE BUFFERS */ 
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TA =* LA; 
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DO WHILE L < TA; 
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CALL SETMEM (0); LA » LA+1; 
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END; 
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/* PRINT FINAL STATISTICS */ 
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CALL PRINT(. 'FIRST ADDRESS $'); CALL PRINTADDR ( SA) ; 
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CALL PRINTU'LAST ADDRESS $') ; CALL PRINTADDR (FA) ; 


00317 


3 


CALL PRINT(. 'BYTES READ $'); CALL PRINTADDR (NB) ; 


00318 


3 


CALL PRINT (. 'RECORDS WRITTEN $'); CALL PRINTHEX(P); 


00319 


3 


CALL CRLF; 


00320 


3 




00321 


3 


END RELOC ; 


00322 


2 




00323 


2 


/* ARRIVE HERE FROM THE SYSTEM MONITOR, READY TO READ THE'* 


HEX TAPE 




00324 


2 




00325 


2 


/* SET UP STACKPOINTER IN THE LOCAL AREA */ 


00326 


2 


DECLARE STACK(16) ADDRESS, SP ADDRESS; 


00327 


2 


SP « STACKPOINTER; STACKPOINTER = .STACK (LENGTH (STACK) ) ; 


00328 


2 




00329 


2 


SBP * LENGTH (SBUFF) ; 


00330 


2 


/* SET UP THE SOURCE FILE */ 


00331 


2 


CALL MOVE (FCBA, .SFCB , 33) ; 


00332 


2 


CALL MOVE(. ('HEX',0) ,.SFCB(9) ,4) ; 


00333 


2 


CALL SEARCH (.SFCB) ; 


00334 


2 


IF (RFLAG := DCNT = 255) THEN 


00335 


2 


CALL PRINT (. 'SOURCE IS READER$') ; ELSE 


00336 


2 


DO; CALL PRINT (. 'SOURCE IS DISK$ ' ) ; 



4 



00337 


3 


00338 


3 


E$') ; 




00339 


3 


00340 


2 


00341 


2 


00342 


2 


00343 


2 


00344 


2 


00345 


2 


00346 


2 


00347 


2 


00348 


2 


) ; ELSE 




00349 


2 


00350 


3 


00351 


3 


'); 




00352 


3 


00353 


2 


00354 


2 


00355 


2 


00356 


2 


00357 


2 


00358 


2 


00359 


1 


00360 


1 



CALL OPEN(.SFCB) ; 

IF DCNT = 255 THEN CALL PRINT (. '-CANNOT OPEN SOURC 



END; 
CALL CRLF; 

CALL MOVE(. 'COM' ,FCBA+9,3) ; 



38 



/* REMOVE ANY EXISTING FILE BY THIS NAME */ 

CALL DELETE (FCBA) ; 

/* THEN OPEN A NEW FILE */ 

CALL MAKE (FCBA) ; FCB(32) - 0; /* CREATE AND SET NEXT RECORD */ 
IF DCNT = 255 THEN CALL PRINT (.'NO MORE DIRECTORY SPACE$ ' 

DO; CALL RELOC ; 
CALL CLOSE (FCBA) ; 

IF DCNT = 255 THEN CALL PRINT ( • 'CANNOT CLOSE FILE$ 

END; 
CALL CRLF ; 

/* RESTORE STACKPOINTER FOR RETURN */ 
STACKPOINTER = SP; 
RETURN 0; 
END LOADCOM; 

EOF 



* 



